Storing and tracking code and text

Purpose: Archival copy of software and document source, plus synchronization across computers

What is Git?

Git is a tool for Version Control. Version Control is a tool for managing changes to files. According to Software Carpentry, it is better than Dropbox and Email because:

  • Nothing that is committed to version control is ever lost. Since all old versions of files are saved, it’s always possible to go back in time to see exactly who wrote what on a particular day, or what version of a program was used to generate a particular set of results.

  • As we have this record of who made what changes when, we know who to ask if we have questions later on, and, if needed it, revert to a previous version, much like the “undo” feature in an editor.

  • When several people collaborate in the same project, it’s possible to accidentally overlook or overwrite someone’s changes: the version control system automatically notifies users whenever there’s a conflict between one person’s work and another’s.

What is GitHub?

GitHub is a website that lets you share git repositories (collections of code) on it. It also gives you a web interface for reading and reviewing code. GitHub isn't the only website that does this, but it's the most common one. It's also the one used for Nengo and the CTN's other projects.

How to GitHub?

To learn how to use Git and GitHub in a thorough manner, going through the Software Carpentry Tutorial on Git is highly recommended. However, the aforementioned tutorial does not cover branches, an important feature of how Nengo uses Git, which are covered in this seperate tutorial in the same style as Software Carpentry.

Basically, if you want to make changes to code on GitHub, you'll generally follow the following pattern:

  • Get the code using -> git clone <repositoryurl>
  • Make a new branch for you edits -> git checkout -b <newbranch>
  • Edit the code
  • Stage your changes using -> git add <filechanged>
  • Commit your changes -> git commit -m "<commitmessage>
  • Push the branch to GitHub -> git push origin <newbranch>
  • Make a pull request for the branch on GitHub, which will be reviewed by the maintainers of the repository before being merged onto the master branch

If you just want some commands to add your code to Nengo, see the next section.

How Nengo use GitHub

Nengo uses a strict set of rules for using git to ensure that the history of the master branch is clean and readable.

  1. Every commit in the master branch should pass testing, including static checks like flake8 and pylint.
  2. Commit messages must follow guidelines.
  3. Developers should never edit code on the master branch. When changing code, create a new topic branch for your contribution. When your branch is ready to be reviewed, push it to Github and create a pull request.
  4. Pull requests must be reviewed by at least two people before merging. There may be a fair bit of back and forth before the pull request is accepted.
  5. Pull requests cannot be merged by the creator of the pull request.
  6. Only maintainers, can merge pull requests to ensure that the history remains clean.

Here is a handy summary of the commands you'll probably need (with commit and add ommitted, since they're very basic):

  • Make a new branch

      git branch <newbranch>
      git checkout <newbranch>
  • Shortcut! Make a new branch

      git checkout -b <newbranch>
  • Push a new branch to a remote (in this case origin)

      git push origin <newbranch>
  • Delete a branch locally

      git branch -D <newbranch>
  • Delete a branch on a remote (in this origin)

      git push origin :<newbranch>
  • Update master and rebase your branch to master

      git checkout master
      git pull
      git checkout <newbranch>
      git rebase master
  • Check out a remote branch (after pulling to see that there is a branch)

      git checkout --track -b <newbranch> origin/<newbranch>
  • (For maintainers) Clean up commits on a branch (prepping for merge)

      git checkout <branchtomerge>
      git rebase master
      git rebase -i <commit>  # if you want to edit the history
  • (For maintainers) Merge a cleaned up branch

      git checkout master
      git merge <cleanbranch>
      # Ensure that the history looks clean before pushing!

How should I use GitHub for my own project?

Given you're probably going to be collaborating with only one other person and you just want GitHub to be a nice public place for you to both put your code, you probably won't need as strict of a workflow as Nengo. You'll probably be fine working directly off the master branch. In other words you won't make a new branch every time you want to change code. This is sometimes called the Centralised Workflow.

However, if conflicts start to become a problem, creating branches and reviewing before merging code is recommended. This is sometimes called the Feature Branch Workflow.

Bonus stuff not covered in this talk

GitHub and Continuous Integration

Automate checking that branches meet style guidelines and pass tests. Performed on Nengo with TravisCI.

Viewing code history on GitHub

GitHub has many tools for viewing who changed what and where they changed it.